<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Using Zend_Layout - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/learning.layout.usage.html">Inglês (English)</a></li>
    <li><a href="../pt-br/learning.layout.usage.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="learning.layout.intro.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="learning.layout.html">Getting Started with Zend_Layout</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="learning.layout.conclusions.html">Zend_Layout: Conclusions</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="learning.layout.usage" class="section"><div class="info"><h1 class="title">Using Zend_Layout</h1></div>
    

    <p class="para">
        Basic usage of <span class="classname">Zend_Layout</span> is fairly trivial. Assuming you&#039;re using
        <span class="classname">Zend_Application</span> already, you can simply provide some configuration
        options and create a layout view script.
    </p>

    <div class="section" id="learning.layout.usage.configuration"><div class="info"><h1 class="title">Layout Configuration</h1></div>
        

        <p class="para">
            The recommended location of layouts is in a &quot;<var class="filename">layouts/scripts/</var>&quot;
            subdirectory of your application:
        </p>

        <pre class="programlisting brush: text">
application
|-- Bootstrap.php
|-- configs
|   `-- application.ini
|-- controllers
|-- layouts
|   `-- scripts
|       |-- layout.phtml
</pre>


        <p class="para">
            To initialize <span class="classname">Zend_Layout</span>, add the following to your
            configuration file (&quot;<var class="filename">application/configs/application.ini</var>&quot;):
        </p>

        <pre class="programlisting brush: dosini">
resources.layout.layoutPath = APPLICATION_PATH &quot;/layouts/scripts&quot;
resources.layout.layout = &quot;layout&quot;
</pre>


        <p class="para">
            The first line indicates where to look for layout scripts; the second line gives the
            name of the layout to use, minus the view script extension (which is assumed to be
            &quot;<var class="filename">.phtml</var>&quot; by default).
        </p>
    </div>

    <div class="section" id="learning.layout.usage.layout-script"><div class="info"><h1 class="title">Create a Layout Script</h1></div>
        

        <p class="para">
            Now that you have your configuration in place, you need to create your layout script.
            First, make sure that you&#039;ve created the
            &quot;<var class="filename">application/layouts/scripts</var>&quot; directory; then,
            open an editor, and create the markup for your layout. Layout scripts are simply view
            scripts, with some slight differences.
        </p>

        <pre class="programlisting brush: php">
&lt;html&gt;
&lt;head&gt;
    &lt;title&gt;My Site&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;?php echo $this-&gt;layout()-&gt;content ?&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>


        <p class="para">
            In the example above, you&#039;ll note the call to a  <span class="methodname">layout()</span> view
            helper. When you register the <span class="classname">Zend_Layout</span> resource, you also gain
            access to both an action and view helper that allow you access to the
            <span class="classname">Zend_Layout</span> instance; you can then call operations on the layout
            object. In this case, we&#039;re retrieving a named variable, <var class="varname">$content</var>,
            and echoing it. By default, the <var class="varname">$content</var> variable is populated for
            you from the application view script rendered. Otherwise, anything you&#039;d normally do
            in a view script is perfectly valid -- call any helpers or view methods you desire.
        </p>

        <p class="para">
            At this point, you have a working layout script, and your application is informed of its
            location and knows to render it.
        </p>
    </div>

    <div class="section" id="learning.layout.usage.access"><div class="info"><h1 class="title">Accessing the Layout Object</h1></div>
        

        <p class="para">
            On occasion, you may need direct access to the layout object. There are three ways you
            can do this:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    <em class="emphasis">Within view scripts:</em> use the
                     <span class="methodname">layout()</span> view helper, which returns the
                    <span class="classname">Zend_Layout</span> instance registered with the front controller
                    plugin.
                </p>

                <pre class="programlisting brush: php">
&lt;?php $layout = $this-&gt;layout(); ?&gt;
</pre>


                <p class="para">
                    Since it returns the layout instance, you can also simply call methods on it,
                    rather than assigning it to a variable.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">Within action controllers:</em> use the
                     <span class="methodname">layout()</span> action helper, which acts just like the view
                    helper.
                </p>

                <pre class="programlisting brush: php">
// Calling helper as a method of the helper broker:
$layout = $this-&gt;_helper-&gt;layout();

// Or, more verbosely:
$helper = $this-&gt;_helper-&gt;getHelper(&#039;Layout&#039;);
$layout = $helper-&gt;getLayoutInstance();
</pre>


                <p class="para">
                    As with the view helper, since the action helper returns the layout instance,
                    you can also simply call methods on it, rather than assigning it to a variable.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">Elsewhere: </em> use the static method
                     <span class="methodname">getMvcInstance()</span>. This will return the layout instance
                    registered by the bootstrap resource.
                </p>

                <pre class="programlisting brush: php">
$layout = Zend_Layout::getMvcInstance();
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">Via the bootstrap: </em> retrieve the layout resource, which
                    will be the <span class="classname">Zend_Layout</span> instance.
                </p>

                <pre class="programlisting brush: php">
$layout = $bootstrap-&gt;getResource(&#039;Layout&#039;);
</pre>


                <p class="para">
                    Anywhere you have access to the bootstrap object, this method is preferred over
                    using the static  <span class="methodname">getMvcInstance()</span> method.
                </p>
            </li>
        </ul>
    </div>

    <div class="section" id="learning.layout.usage.other-operations"><div class="info"><h1 class="title">Other Operations</h1></div>
        

        <p class="para">
            In most cases, the above configuration and layout script (with modifications) will get
            you what you need. However, some other functionality exists you will likely use sooner
            or later. In all of the following examples, you may use one of the <a href="learning.layout.usage.html#learning.layout.usage.access" class="link">methods listed above</a> for retrieving
            the layout object.
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    <em class="emphasis">Setting layout variables</em>.
                    <span class="classname">Zend_Layout</span> keeps its own registry of layout-specific
                    view variables that you can access; the <var class="varname">$content</var> key noted in
                    the initial layout script sample is one such example. You can assign and
                    retrieve these using normal property access, or via the
                     <span class="methodname">assign()</span> method.
                </p>

                <pre class="programlisting brush: php">
// Setting content:
$layout-&gt;somekey = &quot;foo&quot;

// Echoing that same content:
echo $layout-&gt;somekey; // &#039;foo&#039;

// Using the assign() method:
$layout-&gt;assign(&#039;someotherkey&#039;, &#039;bar&#039;);

// Access to assign()&#039;d variables remains the same:
echo $layout-&gt;someotherkey; // &#039;bar&#039;
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">disableLayout()</span>. Occasionally, you may want to disable
                    layouts; for example, when answering an Ajax request, or providing a RESTful
                    representation of a resource. In these cases, you can call the
                     <span class="methodname">disableLayout()</span> method on your layout object.
                </p>

                <pre class="programlisting brush: php">
$layout-&gt;disableLayout();
</pre>


                <p class="para">
                    The opposite of this method is, of course,
                     <span class="methodname">enableLayout()</span>, which can be called at any time to
                    re-enable layouts for the requested action.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">Selecting an alternate layout</em>: If you have multiple
                    layouts for your site or application, you can select the layout to use at any
                    time by simply calling the  <span class="methodname">setLayout()</span> method. Call it
                    by specifying the name of the layout script without the file suffix.
                </p>

                <pre class="programlisting brush: php">
// Use the layout script &quot;alternate.phtml&quot;:
$layout-&gt;setLayout(&#039;alternate&#039;);
</pre>


                <p class="para">
                    The layout script should reside in the <var class="varname">$layoutPath</var> directory
                    specified in your configuration. <span class="classname">Zend_Layout</span> will then
                    use this new layout when rendering.
                </p>
            </li>
        </ul>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="learning.layout.intro.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="learning.layout.html">Getting Started with Zend_Layout</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="learning.layout.conclusions.html">Zend_Layout: Conclusions</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="learning.html">Learning Zend Framework</a></li>
  <li class="header up"><a href="learning.layout.html">Getting Started with Zend_Layout</a></li>
  <li><a href="learning.layout.intro.html">Introduction</a></li>
  <li class="active"><a href="learning.layout.usage.html">Using Zend_Layout</a></li>
  <li><a href="learning.layout.conclusions.html">Zend_Layout: Conclusions</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>